NetBSD Documentation: NetBSD IPsec

This page is developing, and we welcome any comments or suggestions.

IPsec FAQ

• Getting Started
• IPsec = AH + ESP + IPcomp + IKE
• Transport mode and tunnel mode
• IPsec "policy" management
• Configuring IPsec kernel
• Configuration examples: host-to-host encryption
• Configuration examples: host-to-host authentication
• Configuration examples: host-to-host encryption+authentication
• Configuration examples: VPN
• Configuring AH/ESP keys by using IKE
• Setting up IPsec manual keys and policies on bootstrap
• Common pitfalls, and debugging techniques
• Known issues
• Conformance to standard, interoperability
• API compatibility with other IPsec stacks

Other links

• KAME project, where the IPv6 implementation come from
• /sys/netinet6/IMPLEMENTATION: detailed information on the implementation
• latest version of the above, for the latest KAME kit (may not be relevant to NetBSD)
• implemenation differences between KAME platforms
• Exportability of NetBSD crypto code

IPsec FAQ

Getting Started (top)

IPsec (IP security protocol) code was merged into the NetBSD distributions in June 1999. It will be included in official releases from NetBSD 1.5. IPsec provides per-packet authenticity/confidentiality guarantees between peers communicate using IPsec. IPsec is available for both IPv6 and IPv4.

Note that, however, kernel re-configuration is necessary to use IPsec. It is not turned on for default GENERIC kernel.

Userland code includes IPsec support where possible, by default, so no rebuild of userland is necessary even if you switch between kernel with IPsec, and without IPsec.

If you have pre-1.5 systems, your situation is as follows:

• If you are using NetBSD 1.4.x, you may want to visit KAME project webpage for IPsec support patches. KAME project supplies IPv6/IPsec patches in single tar.gz file. IPsec portion is usable for both IPv4 and IPv6.
• If you are using NetBSD-current before late November 1999, use of special kernel configuration file (GENERIC.v6) is required to use IPsec.
• If you are using NetBSD-current after November 21 1999, GENERIC kernel configuration file includes IPsec support by default, commented out.
• Before June 2000, crypto source code is distributed separately. Upgrade to more recent tree, or see how to construct build tree in the old distribution system. If you are using NetBSD-current after June 2000, crypto source code is integrated into the base tree.

NOTE: We sometimes use the word "IP security" in more broader sense, like IP firewalls, packet filtering, and so forth.

IPsec = AH + ESP + IPcomp + IKE (top)

IPsec consists of a couple of separate protocols, listed below:

• Authentication Header (AH): provides authenticity guarantee for packets, by attaching strong crypto checksum to packets. If you receive a packet with AH and the checksum operation was successful, you can be sure about two things if you and the peer share a secret key, and no other party knows the key:
  • The packet was originated by the expected peer. The packet was not generated by impersonator.
  • The packet was not modified in transit.
  Unlike other protocols, AH covers the whole packet, from the IP header to the end of the packet.
• Encapsulating Security Payload (ESP): provides confidentiality guarantee for packets, by encryptiong packets with encryption algorithms. If you receive a packet with ESP and successfully decrypted it, you can be sure that the packet was not wiretapped in the middle, if you and the peer share a secret key, and no other party knows the key.
• IP payload compression (IPcomp): ESP provides encryption service to the packets. However, encryption tend to give negative impact to compression on the wire (such as ppp compression). IPcomp provides a way to compress packet before encryption by ESP (Of course, you can use IPcomp alone if you wish to).
• Internet Key Exchange (IKE): As noted above, AH and ESP needs shared secret key between peers. For commuincation between distant location, we need to provide ways to negotiate keys in secrecy. IKE will make it possible.

AH, ESP and IPcomp are implemented in the kernel code. IKE is implemented as daemon process in the userland. Kernel part and userland part will cooperate by using key management table inbetween.

IKE is actually optional, you can configure secret keys manually for AH/ESP. However, please understand it: you cannot use the same secret key forever. If you use the same secret key for a long period of time, your traffic become more and more likely to get compromised.

NOTE: security of IPsec protocols depend on the secrecy of secret keys. If secret keys are compromised, IPsec protocols can no longer be secure. Take caution about permission mode of configuration files, key database files, or whatever thay may lead to information leakage.

There two set of RFCs published; old IPsec suite starts from RFC1825, and new IPsec suite starts from RFC2401. Though NetBSD implements both, it is recommended to new IPsec suite.

	userland programs		IKE daemon
	  ^ | AF_INET{,6} socket	  ^ | PF_KEY socket
========= | | =========================== | | ======== Kernel/user boundary
	  | v				  | v
	transport layer, TCP/UDP	key management table
	  ^ |				  ^ | key information
	  | |				  | |
	  | v				  | v
	IP input/output logic <------->	AH/ESP/IPcomp logic
	  ^ |
	  | v
	Network drivers (ethernet)

Transport mode and tunnel mode (top)

AH, ESP and IPcomp have two modes of operation: transport mode and tunnel mode. Transport mode encrypts normal communication between peers. Tunnel mode will encapsulate packet into new IPv4/v6 header. Tunnel mode is designed to be used by VPN gateways.

[[transport mode]]
my host ======== peer's host
	transport
	mode

packets: [IP: me->peer] ESP payload
			<---------> encrypted


[[tunnel mode]]
	(a)		     (b)			(c)
my host ---- my VPN gateway ======== peer's VPN gateway ---- peer's host
			    tunnel mode

packets on (a): [IP: me->peer] payload
packets on (b): [IP: mygw->peergw] ESP [IP: me->peer] payload
			  	   <------------------------> encrypted
packets on (c): [IP: me->peer] payload

IPsec "policy" management (top)

Though the kernel knows how to secure packets, it does not know which packet requires security. We need to tell kernel about which packet needs to be secured. IPsec "policy" configuration allows us to specify it.

IPsec policy can be configured in per-packet, or per-socket manner:

• Per-packet: configured into the kernel just like packet filters. You can specify like "encrypt outgoing packets if I'm sending to 10.1.1.0/24". This works well when you are running an IPsec router.
• Per-socket: configured via setsockopt(2) for a certain socket. You can specify like "encrypt outgoing packets from this socket". This works well when you would like to run IPsec-aware server program.

IPsec policy decides which IPsec protocols (AH, ESP or IPcomp) to be used against a packet. You can configure kernel to use any combination of AH, ESP and IPcomp against a packet. You can even apply same protocol multiple times, like multiple ESP operation against single packet. It is questionable if multiple ESP operation has any benefit, but certainly interesting for test/debug use.

Configuring IPsec kernel (top)

Refer to tracking NetBSD-current for more details of the build process.

1. In your kernel configuration file, enable the following portion and build a new kernel.

   options IPSEC
   options IPSEC_ESP
   

2. Build a new kernel as usual.
3. Replace the kernel and reboot.

Userland tools include IPsec support by default, and no userland rebuild is necessary.

Additionally, you may want to install racoon and/or isakmpd.

Configuration examples: host-to-host encryption (top)

If you would like to run host-to-host (transport mode) encryption with manually configured secret keys, the following configuration should be enough. We use setkey(8) to configure manual keys.

#! /bin/sh
#
# packet will look like this: IPv4 ESP payload
# the node is on 10.1.1.1, peer is on 20.1.1.1
setkey -c <<EOF
add 10.1.1.1 20.1.1.1 esp 9876 -E 3des-cbc "hogehogehogehogehogehoge";
add 20.1.1.1 10.1.1.1 esp 10000 -E 3des-cbc "mogamogamogamogamogamoga";
spdadd 10.1.1.1 20.1.1.1 any -P out ipsec esp/transport//use;
EOF

First two lines configure secret keys to be used by ESP. The decimal numbers appar as the fourth word are called SPI (security parameter index). The value will be attached to ESP packet, and it lets receiving side to lookup secret key from the packet. The number needs to be unique on a node.

• From 10.1.1.1 to 20.1.1.1, we'd use 3DES-CBC algorithm, with secret key "hogehogehogehogehogehoge". The traffic will be identified by SPI 9876.
• From 20.1.1.1 to 10.1.1.1, we'd use 3DES-CBC algorithm, with secret key "mogamogamogamogamogamoga". The traffic will be identified by SPI 10000.

The last line configures per-packet IPsec policy for the node. With the configuration, the node (10.1.1.1) to transmit packets to the peer (20.1.1.1) encrypted, whenever secret key is configured into the kernel. The configuration does not prohibit unencrypted packets from 20.1.1.1 to reach 10.1.1.1. If you would like to reject unencrypted packet, add the following line:

spdadd 10.1.1.1 20.1.1.1 any -P in ipsec esp/transport//require;

On the other end (20.1.1.1), the configuration will be like this. Note that there's no difference in "add" lines.

#! /bin/sh
#
# packet will look like this: IPv4 ESP payload
# the node is on 20.1.1.1, peer is on 10.1.1.1
setkey -c <<EOF
add 10.1.1.1 20.1.1.1 esp 9876 -E 3des-cbc "hogehogehogehogehogehoge";
add 20.1.1.1 10.1.1.1 esp 10000 -E 3des-cbc "mogamogamogamogamogamoga";
spdadd 20.1.1.1 10.1.1.1 any -P out ipsec esp/transport//use;
EOF

The syntax for policy configuration is documented in ipsec_set_policy(3).

Try running tcpdump(8) to see the encrypted packets on the wire - they are encrypted, it is no longer possible to wiretap those packets.

The above exampe uses human-readable secret keys. However, use of human-readable secret key is discouraged by the specification (since it will have more chance to be compromised, than binary keys). You'd better use binary keys for real operation.

Key length is determined by algorithms. For 3des-cbc, the secret key MUST be 192 bits (= 24 bytes). If you specify shorter/longer key, you will get error from setkey(8).

If you wish to use other algorithms, the configuration is very similar. Here's an example with rijndael-cbc (also known as AES). rijndael-cbc takes 128, 192 or 256 bits of secret keys.

#! /bin/sh
#
# packet will look like this: IPv4 ESP payload
# the node is on 10.1.1.1, peer is on 20.1.1.1
# rijndael-cbc with 128bit key
setkey -c <<EOF
add 10.1.1.1 20.1.1.1 esp 9876 -E rijndael-cbc "hogehogehogehoge";
add 20.1.1.1 10.1.1.1 esp 10000 -E rijndael-cbc "mogamogamogamoga";
spdadd 10.1.1.1 20.1.1.1 any -P out ipsec esp/transport//use;
EOF

Configuration examples: host-to-host authentication (top)

Just like ESP, you can configure AH.

#! /bin/sh
#
# packet will look like this: IPv4 AH payload
# the node is on 10.1.1.1, peer is on 20.1.1.1
setkey -c <<EOF
add 10.1.1.1 20.1.1.1 ah 9877 -A hmac-md5 "hogehogehogehoge";
add 20.1.1.1 10.1.1.1 ah 10001 -A hmac-md5 "mogamogamogamoga";
spdadd 10.1.1.1 20.1.1.1 any -P out ipsec ah/transport//use;
EOF

Configuration examples: host-to-host encryption+authentication (top)

If you configure secret keys for both AH and ESP, you can use both of them. IPsec document suggests to apply AH after ESP.

#! /bin/sh
#
# packet will look like this: IPv4 AH ESP payload
# the node is on 10.1.1.1, peer is on 20.1.1.1
setkey -c <<EOF
add 10.1.1.1 20.1.1.1 esp 9876 -E 3des-cbc "hogehogehogehogehogehoge";
add 20.1.1.1 10.1.1.1 esp 10000 -E 3des-cbc "mogamogamogamogamogamoga";
add 10.1.1.1 20.1.1.1 ah 9877 -A hmac-md5 "hogehogehogehoge";
add 20.1.1.1 10.1.1.1 ah 10001 -A hmac-md5 "mogamogamogamoga";
spdadd 10.1.1.1 20.1.1.1 any -P out ipsec esp/transport//use ah/transport//use;
EOF

Configuration examples: VPN (top)

The following example assumes the folloinwg network configuration, and presents configuration for gateway 1 (:

((( 10.0.1.0/24 )))	VPN'ed network
  |10.0.1.1
gateway 1
  |20.0.0.1
  |IPsec tunel
  |20.0.0.2
gateway 2
  |10.0.2.1
((( 10.0.2.0/24 )))	VPN'ed network

#! /bin/sh
#
# Note that routing should be set up in advance, i.e. for this example:
#	route -n add -net 10.0.2.0 10.0.2.1
#	route -n add 10.0.2.1 10.0.1.1
# packet will look like this: IPv4 ESP IPv4 payload
# the node is on 10.0.1.1/20.0.0.1, peer is on 10.0.2.1/20.0.0.2
setkey -c <<EOF
add 20.0.0.1 20.0.0.2 esp 13245 -E blowfish-cbc "blowfishtest.001" ;
add 20.0.0.2 20.0.0.1 esp 13246 -E blowfish-cbc "blowfishtest.002" ;
spdadd 10.0.1.0/24 10.0.2.0/24 any -P out ipsec esp/tunnel/20.0.0.1-20.0.0.2/req
uire ; 
spdadd 10.0.2.0/24 10.0.1.0/24 any -P in ipsec esp/tunnel/20.0.0.2-20.0.0.1/requ
EOF

(contributed by Per Harald Myrvang)

Configuring AH/ESP keys by using IKE (top)

Here we describe the following configuration:

• Node A and B will use transport-mode ESP.
• It is required for both ends to use ESP to exchange packets, for all protocols.
• During IKE, node A and B authenticate each other by using shared secret exchange.

Please follow the steps carefully. Run tcpdump(8) to check how the packets are exchanged between two nodes. Statistics by "netstat -sn" is also useful to know how kernel IPsec portion is working.

1. Build and install racoon, more recent than 20000923a.
2. Copy /usr/pkg/share/examples/racoon/racoon.conf.sample into /etc/racoon/racoon.conf. Modify parameters declared in racoon.conf as necessary. It is VERY critical that both ends use the same configuration - you will want less differences in racoon.conf.
3. racoon will obey the IPsec policy settings in the kernel when it negotiates IPsec keys. Therefore, we need to confiugre IPsec policy into the kernel by using setkey(8). On node A, configure IPsec policy like this. In the example, "A" and "B" are IPv4/v6 numeric addresses.

   A# setkey -c
   spdadd A B any -P out ipsec esp/transport//require;
   spdadd B A any -P in ipsec esp/transport//require;
   ^D
   

4. On node B, configure IPsec policy like this by using setkey(8):

   B# setkey -c
   spdadd B A any -P out ipsec esp/transport//require;
   spdadd A B any -P in ipsec esp/transport//require;
   ^D
   

5. On both nodes, prepare pre-shared key file. It is VERY critical to set file permission properly, otherwise it worth nothing to use IPsec - it will do nothing other than wasting your CPU time (racoon will not read files with weak permissions). Again "A" and "B" are numeric IPv4/v6 addresses.

   A# cat >/etc/racoon/psk.txt
   B	spamspamspam
   ^D
   A# chmod 600 /etc/racoon/psk.txt
   
   B# cat >/etc/racoon/psk.txt
   A	spamspamspam
   ^D
   B# chmod 600 /etc/racoon/psk.txt
   

6. Run /usr/pkg/sbin/racoon. If you wish see the debug trace, arguments would be like below:

   # /usr/pkg/sbin/racoon -f /etc/racoon/racoon.conf -d 0xffffffff
   

7. Try to exchange packet between A and B. You will see some messages from racoon to console, and key will be established.

   A# ping -n B
   (with some delay, you will start seeing replies)
   ^C
   A# setkey -D
   (you will see keys exchanged by racoon)
   

racoon will negotiate keys based on the policy definition. By changing policy definition, we can easily configure for other cases. Next example configure keys for the following situation:

• A is a mail server. A wishes to enforce the use of transport mode AH, to everyone contacts A with POP protocol (TCP port 110). B is a client which wishes to contact A.

1. The policy configuration on A avoids of AH for local traffic (note that racoon cannot negotiate keys with itself). The order of the policy is highly important. If you reorder them, the configuration will not work.

   A# setkey -c
   spdadd A[110] A tcp -P out none;
   spdadd A A[110] tcp -P in none;
   spdadd A[110] 0.0.0.0/0 tcp -P out ipsec ah/transport//require;
   spdadd 0.0.0.0/0 A[110] tcp -P in ipsec ah/transport//require;
   ^D
   
   B# setkey -c
   spdadd B A[110] tcp -P out ipsec ah/transport//require;
   spdadd A[110] B tcp -P in ipsec ah/transport//require;
   ^D
   

2. Other than policy configuration part, configure just like the previous example.

If you have any problem in configuring it, be sure to look at full debug logs (racoon -d 0xffffffff) and see where it chokes. Every configuration difference leads to unsuccessful negotiation.

Setting up IPsec manual keys and policies on bootstrap (top)

rc.conf(5) has an entry for IPsec, named "ipsec". ipsec=YES will run the following command at bootstrap time, before any of the network activities (you can perform encrypted NFS mount for /usr, for example). /etc/ipsec.conf should contain valid setups to setkey(8). Consult rc.conf(5) for detail.

/sbin/setkey -c < /etc/ipsec.conf

Common pitfalls, and debugging techniques (top)

• Some people mix up the following three items. Take caution if you try to interoperate with other implementations. If you mix them up, you will never be able to make a interoperable configuration. Documentations may be using different words for them (sigh).
  • IPsec with manual key
    In NetBSD case, this way uses setkey(8) to configure IPsec secret key. IPsec secret key will not change over time.
  • IPsec with IKE, with pre-shared secret
    In NetBSD case, this uses racoon. We authenticate peer with pre-shared secret. racoon will negotiate IPsec keys dynamically and installs it into the kernel. IPsec secret key changes over time.
  • IPsec with IKE, with certificates
    In NetBSD case, this uses racoon. We authenticate peer with certificate files. racoon will negotiate IPsec keys dynamically and installs it into the kernel. IPsec secret key changes over time.
• The configuration of IPsec is NOT EASY. There are way too many knobs to play with, and debugging is very hard due to wiretap-resistant nature of IPsec. Basically, we can't guess what is going on from packet trace. Try reading some books and standard documents/RFCs, hire consultants or whatever, before you try to configure it.
• Always run tcpdump while you debug the network. Even though the traffic is encrypted, you can get some idea if the packet is really on the wire or not.
• netstat(1) is your friend. Run netstat -sn and check the IPsec packet counters.
• If you have trouble running racoon, try running it with maximum debugging output and look at the output. (command line argument -d 0xffffffff)
• You really really need to configure your NetBSD device with peer's device exactly the same to make them interoperate.

Known issues (top)

• Tunnel mode AH does not work as you might expect, due to restrictions in kernel IPsec policy engine. Do not try to use tunnel mode AH.
• racoon is still under devevlopment and has certain tweaks and/or missing items. See pkg/DESCR supplied with racoon for more info.

Conformance to standard, interoperability (top)

KAME IPsec implementation (which is included in NetBSD tree) conforms to latest set of IPsec standards. /sys/netinet6/IMPLEMENTATION has comprehensive list of standard documents to which the implementation conforms.

Interoperability with other implementation has been confirmed in various occasions. /sys/netinet6/IMPLEMENTATION includes list of implementations which we have confirmed interoperability in the past. Note that, however, it is possible for both sides to change the code after interoperability tests, and it is possible that they no longer interoperate. It is also possible that NetBSD device and peer's device interoperate in certain configuration only.

If you try to configure NetBSD device with other implementation, please note that IPsec specifications/implementations have too many knobs to play with. You need to configure your NetBSD device with peer's device exactly the same to make them interoperate.

API compatibility with other IPsec stacks (top)

If you write userland code that is aware of IPsec, you may become curious about API compatibility across IPsec platforms.

We have RFC2367 PF_KEY API for manipulating secret key database in the kernel. Basic portion of this API is available on other UNIX-based IPsec stacks as well, and may be compatible to certain degree (for example, OpenBSD implements PF_KEY API as well). KAME IPsec stack extends this in certain way, just like other parties do. Extended portion is not compatible with other (non-KAME) IPsec stacks.

There is no document that specifies IPsec policy management API. Therefore, we can expect no compatibility with (non-KAME) IPsec stacks in IPsec policy management API.

There is no standard for configuration file syntax. You will need to convert them if you would like to copy configuration from/to non-NetBSD IPsec devices.

Since NetBSD and FreeBSD share IPsec codebase from the same origin (KAME), there is a good chance for API compatibility. Note that, however, there are differences in NetBSD IPsec code and FreeBSD IPsec code, since they merged in KAME code of different date. As of writing, normal userland applications do not need to worry about the difference:

• NetBSD-current incorporates KAME IPsec stack of early June 2000.
• FreeBSD 4.0-RELEASE incorporates KAME IPsec stack of early November 1999.
• FreeBSD-current incorporates KAME IPsec stack of early November 1999.
• There is no difference in manual ipsec key configuration, kernel behavior on AH/ESP operation, or ipsec_set_policy(3) API.
• There are differences in behavior of PF_KEY socket, libipsec API for PF_KEY wrapper functions and several other locations. The difference may bite you if you want to implement application that manipulates PF_KEY socket directly (i.e. IKE daemon like racoon or key config program like setkey(8)).

During NetBSD-current development between NetBSD 1.4 to NetBSD 1.5, we have imported KAME IPsec portion three times. Those imports contain backward-incompatible changes in the API. Please make sure to use the latest code, if you are on NetBSD-current between 1.4 and 1.5. Once NetBSD 1.5 is get shipped, we will provide complete binary compatibility, or API version number check, to the API present in NetBSD 1.5.

Home Page

Documentation top level